_cimtools documentation - by the reverend
rev. 0 - initial release

* this document best viewed in a fixed-width font like courier or terminal.

TABLE OF CONTENTS
  1. introduction
  2. script.ini
  3. _ztm
  4. _cim
  5. _cimtool
  6. future development
  7. disclaimers

1. INTRODUCTION

_cimtools is a high-quality, FREE, package for ZOC 4.04+ that performs all kinds of data management for tradewars.  it keeps track of cim (port and sector) information only - not figs, mines, planets, ships, etc.

the _cimtools package includes:

  help files:
    _cimtools.txt
  scripts:
    _ztm.zrx     - performs zero-turn-mapping (ztm)
    _cim.zrx     - gathers computer-interrogation-mode (cim) data
    _cimtool.zrx - sorts, merges, and arranges cim data into appropriate data files
  programs:
    PMAP2.EXE    - parser program for map files (written by the reverend)
  info files:
    script.ini   - basic info file used by scripts

the _cimtools package will create the following output files:

  [cimname].sct     - standard sector cim created by _cim.zrx
  [cimname]_ref.sct - reference sector cim created by PMAP2.EXE
  [cimname].prt     - standard port cim created by _cim.zrx
  [cimname]_ref.prt - reference port cim created by PMAP2.EXE
  [cimname].ztm     - ztm log created by _ztm.zrx
  [cimname].map     - binary map file used by PMAP2.EXE
  [cimname]*.txt    - these are the reports created by PMAP2.EXE

the zoc directory structure looks like this:
  ...\ZOC           - ZOC program directory (usually c:\Program Files\ZOC)
      `-> \SCRIPT   - all scripts, programs, and info files should go here
      `-> \LOG      - all output files will be found here
      `-> \DOWNLOAD - this is where PMAP output will go unless you change the ZOC setting
                      (see chapter 6)

basically, the way the program works is this:  _cim gathers current port and sector information and stores them in standard cim logs.  _cimtools keeps track of all sectors and ports in the reference cim files (.srf and .prf).  in addition, any ztm files can be merged into the reference sector cim file, thus mining the ztm for more sector warp info.  all of this info is merged into a binary map file by _makemap or _cim.  finally, the PMAP2 parser will find one-ways, port pairs, and bubbles (using ztm data too).  it will even tell you which bubbles are explored, which are compromised by one-ways in, and which ports are blocked.

      .-----.
      |     |----------------.
      | cim |\               |
      |     | \  .-----.     v      .-----.
      '-----'  \ |     |    .---.   |     |
                >| ref |--->PMAP2-->| txt |
      .-----.  / |     |    '---'   |     |
      |     | /  '-----'      \     '-----'
      | ztm |/    ^            \    .-----.
      |     |     |             \   |     |   .------------.
      '-----'     .              `->| map |-->| script use |
                 /                  |     |   '------------'
      .------.  /                   '-----'
      |      | /
      | corp |/
      | cims |
      |      |
      '------'


due to selfish desires to hoard some of the goodies to myself, there are additional features in PMAP2 that have been disabled.  sorry <grin>.  however, the software is not designed to give bad information, and no information is withheld.  so if you get a bubble report, then thats all the bubbles that were found.  no port pairs are left out.  no one-ways are ignored.  i'm not screwing you out of good info, i'm just keeping some extra features private.

2. SCRIPT.INI

info files are the basis for the reverend's script library.  when i first started writing scripts i got tired of the usual 10 questions every script had to ask, like:  "how many sectors in universe?"  "where is stardock?"  "what is the steal factor?"  "where is alpha centauri?"  "what is the cim filename?"  etc.  so i devised a simple windows-style .ini file that contained all that info for each game i was playing.  then when you run a script, all it asks you is "which game are you playing".  once you pick a game, all the settings are available without asking you.  thus we have script.ini.

the script.ini file looks like this:

  [gamename]
  corp=3               - corp number (i used these ones for sdr, ssr, etc.)
  corppwd=haha         - corp password
  radio=4532           - subspace channel
  sf=30                - steal factor
  rf=3                 - rob factor
  bustclearfreq=1      - bust clear frequency in days
  extern=24            - extern in 24-hour time (your time, not server time)
  sd=333               - stardock
  alpha=555            - alpha centauri
  rylos=444            - rylos
  cr=600               - carriage return when moving - 600 for 5k / 20001 for 20k
  ns=5000              - number of sectors
  cim=cimname          - cim name (should be 8 characters or less, no spaces)
                         * this is the filename used for cim/ztm logs (see chapter 1)

that is a good summary of the basic elements of a game setup.  most scripts don't need all these variables though.  _cimtools only needs:

  [gamename]
  sd=333
  alpha=555
  rylos=444
  ns=5000
  cim=cimname

in addition, you can set up more than one game in script.ini.  here's mine for example:

  [the orchestra f]
  sf=30
  rf=0.3529
  bustclearfreq=7
  extern=24
  sd=781
  bsd=476
  cr=1001
  ns=1000
  cim=to_f
  
  [vid kid d]
  sf=15
  rf=6
  bustclearfreq=1
  extern=21
  sd=648
  bsd=2631
  cr=600
  ns=5000
  cim=vk_d
  
  [twlinks wtc wu]
  sf=21
  rf=6
  sd=4489
  bsd=4574
  alpha=2824
  rylos=2718
  cr=600
  ns=5000
  cim=tw_b
  
  [twlinks m]
  sf=21
  rf=6
  cr=600
  ns=5000
  cim=tw_m
  
  [LIL FUNKY]
  radio=7523
  sf=3
  rf=30
  bustclearfreq=1
  extern=23
  sd=42
  bsd=81
  alpha=13
  rylos=41
  cr=600
  ns=5000
  cim=lilfunky
  
  [USO 2001]
  pwd=999
  corp=5
  sf=21
  rf=6
  bustclearfreq=1
  extern=23
  sd=145
  bsd=923
  alpha=120
  rylos=430
  cr=600
  ns=5000
  cim=uso

  [MANUAL ENTRY]
  ;this is not really a game section - all variables are missing.
  ;if you choose this entry, the script will ask you for all necessary info.

the basic idea is that you have a section for each game you are playing in your script.ini file.  if you don't have a section defined, then you can select the last section, [MANUAL ENTRY], and then enter the values manually each time you run the script.

3. _CIM

_cim uses ZOC's logging feature to create a log files named [cimname].sct and [cimname].prt.  these files are the basis for all data mining in tradewars.  after grabbing the data, _cim call PMAP2* to create your reports and manage the reference cims.  this way you have a backup record of all sector warps and ports.  then you will know when ports are blocked and what sector information is gathered from ztm analysis.

* PMAP2 will open a DOS shell window when it runs.  this window may be open for up to 30 seconds.

4. _ZTM

_ztm is designed to offer plenty of options for zero turn mapping.  the script uses ZOC's logging feature to create a log file named [cimname].ztm.  there are ztm modes available:

  1-2,3-4,...           - maps pairs 1<->2, 3<->4, ... 4999<->5000
  1-5000,2-4999,...     - maps pairs 1<->5000, 2<->4999, ... 2499<->2500
  random pairs          - maps random pairs
  terra                 - maps all paths from terra (not to terra)
  one-ways              - maps and verifies all one-ways based on the reference cim

this new version of ztm will merge all data into your reference cim files on the fly.  there is no need to run _cimtool.zrx anymore to merge ztm data, although _cimtool.zrx is still included and works the same as before.  the only reason you may need to run _cimtool.zrx is if your corpie sends you their ztm logs and you need to merge them.

if you stop _ztm in the middle - before it finishes - the script will tell you where it left off so you can tell the script where to pick up when you run it again.

5. _CIMTOOL

_cimtool is the heart of the package.  when you run _cimtool, it will automatically load up the reference cim files into memory for processing.  once they are loaded, you can choose options to merge other cim data into the reference files and save them afterward.  the options look like this:

  main menu  
  \\   \   `- merge cim                    - select this option to merge cim data
   \\   \           \\\`- cimname.sct
    \\   \           \\`- cimname.prt
     \\   \           \`- select...
      \\   \           `- cancel
       \\   `- merge ztm                   - select this option to merge ztm data
        \\          \\`- cimname.ztm
         \\          \`- select...
          \\          `- cancel
           \`- save                        - select this option to save new reference files
            `- quit

using _cimtool, you can merge any information you desire - but use caution.  the menu will offer default filenames (if they exist) to merge, i.e. the cim logs created by _cim or the ztm log created by _ztm.  however, you can also get your corpies to send you their cim files and you can merge them into your reference files.  they must have the right extensions, however.  you can only merge a .sct, .prt, or .ztm file.  just choose the "select..." button in the menu and pick the file you want to merge.  if the files are the wrong format, i cannot guarantee results.  i have personally ruined months of data this way - so be careful.

the rewards are greater than the risks, however, especially for bubble information.  the more peoples' cim data you suck into your reference files, the better the bubble data will be.  bubble results will still show "unexplored" even if you use other peoples' cim data because you have personally not visited there.

6. FUTURE DEVELOPMENT

my scripts are always in progress.  i try to make sure i don't release anything that doesn't work, but the project is growing bigger than i have ever imagined, so please send me email with bug reports and i'll be sure to fix them asap.  also, the PMAP2 parser is a work in progress.  at this point, i think its pretty solid, but there are many features that i still want to add.

7. LICENSE

Copyright (C) 2001 Ron Wilson
                                                                        
These scripts are free, and can be modified for your personal use, but you cannot copy or distribute these scripts or any derivative work based upon them without the express permission of the author. Your use of these scripts is governed by the terms of the REV-LICENSE.

These programs are provided to you WITHOUT ANY WARRANTY, even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the REV-LICENSE for more details.

A copy of the REV-LICENSE is available at:  http://thereverend.coastgames.com/rev-license.html